---
title: 全站搜索
description: 了解 Starlight 的内置全站搜索功能和如何自定义它们。
---

import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';

默认情况下，Starlight 站点提供了基于 [Pagefind](https://pagefind.app/) 的全文搜索，它是一个为静态站点的快速且低带宽的搜索工具。

启用搜索不需要配置。构建并部署你的站点，然后使用网站顶部的搜索栏来查找内容。

## 从搜索结果中隐藏内容

### 排除一个页面

要从搜索结果中排除一个页面，需要将 [`pagefind: false`](/zh-cn/reference/frontmatter/#pagefind) 添加到页面的 frontmatter 中：

```md title="src/content/docs/不被索引.md" ins={3}
---
title: 要从搜索结果中隐藏的内容
pagefind: false
---
```

### 排除页面中的一部分

Pagefind 会忽略带有 [`data-pagefind-ignore`](https://pagefind.app/docs/indexing/#removing-individual-elements-from-the-index) 属性的元素内的内容。

在下面的示例中，第一个段落将显示在搜索结果中，但 `<div>` 的内容不会：

```md title="src/content/docs/部分索引.md" ins="data-pagefind-ignore"
---
title: 部分索引的页面
---

这段文字会被搜索到。

<div data-pagefind-ignore>

这段文字不会被搜索到。

</div>
```

## 其他搜索供应商

### Algolia DocSearch

如果你加入了 [Algolia 的 DocSearch 计划](https://docsearch.algolia.com/)并且想要用它来替代 Pagefind，你可以使用官方的 Starlight DocSearch 插件。

<Steps>

1. 安装 `@astrojs/starlight-docsearch`:

   <Tabs syncKey="pkg">

   <TabItem label="npm">

   ```sh
   npm install @astrojs/starlight-docsearch
   ```

   </TabItem>

   <TabItem label="pnpm">

   ```sh
   pnpm add @astrojs/starlight-docsearch
   ```

   </TabItem>

   <TabItem label="Yarn">

   ```sh
   yarn add @astrojs/starlight-docsearch
   ```

   </TabItem>

   </Tabs>

2. 把 DocSearch 加到 `astro.config.mjs` 里你的 Starlight [`plugins`](/zh-cn/reference/configuration/#plugins) 配置中，并传入你的 Algolia `appId`、`apiKey` 和 `indexName`：

   ```js ins={4,10-16}
   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   import starlightDocSearch from '@astrojs/starlight-docsearch';

   export default defineConfig({
   	integrations: [
   		starlight({
   			title: '使用 DocSearch 的网站',
   			plugins: [
   				starlightDocSearch({
   					appId: 'YOUR_APP_ID',
   					apiKey: 'YOUR_SEARCH_API_KEY',
   					indexName: 'YOUR_INDEX_NAME',
   				}),
   			],
   		}),
   	],
   });
   ```

</Steps>

像这样更新配置后，你站点上的搜索栏将会打开一个 Algolia 的模态框而不是默认的搜索模态框。

#### DocSearch 配置

Starlight DocSearch 插件还支持通过下面这些附加的选项来自定义 DocSearch 组件：

- `maxResultsPerGroup`：限制每个搜索组所显示的结果数。默认值为 `5`。
- `disableUserPersonalization`：阻止 DocSearch 将用户的最近搜索和收藏夹保存到本地存储。默认值为 `false`。
- `insights`：启用 Algolia Insights 插件并将搜索事件发送到你的 DocSearch 索引。默认值为 `false`。
- `searchParameters`：一个可用于自定义 [Algolia 搜索参数](https://www.algolia.com/doc/api-reference/search-api-parameters/)的对象。

#### 翻译 DocSearch UI

DocSearch 默认只提供了英语 UI 文本。
使用 Starlight 内置的[国际化系统](/zh-cn/guides/i18n/#翻译-starlight-的-ui)来添加你的语言的模态框 UI 的翻译。

<Steps>

1. 在 `src/content/config.ts` 中给 Starlight 的 `i18n` 内容集合定义添加 DocSearch schema：

   ```js ins={4} ins=/{ extend: .+ }/
   // src/content/config.ts
   import { defineCollection } from 'astro:content';
   import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
   import { docSearchI18nSchema } from '@astrojs/starlight-docsearch/schema';

   export const collections = {
   	docs: defineCollection({ schema: docsSchema() }),
   	i18n: defineCollection({
   		type: 'data',
   		schema: i18nSchema({ extend: docSearchI18nSchema() }),
   	}),
   };
   ```

2. 在 `src/content/i18n/` 里的 JSON 文件中添加翻译。

   这些是 DocSearch 使用的英文默认文本：

   ```json title="src/content/i18n/en.json"
   {
   	"docsearch.searchBox.resetButtonTitle": "Clear the query",
   	"docsearch.searchBox.resetButtonAriaLabel": "Clear the query",
   	"docsearch.searchBox.cancelButtonText": "Cancel",
   	"docsearch.searchBox.cancelButtonAriaLabel": "Cancel",
   	"docsearch.searchBox.searchInputLabel": "Search",

   	"docsearch.startScreen.recentSearchesTitle": "Recent",
   	"docsearch.startScreen.noRecentSearchesText": "No recent searches",
   	"docsearch.startScreen.saveRecentSearchButtonTitle": "Save this search",
   	"docsearch.startScreen.removeRecentSearchButtonTitle": "Remove this search from history",
   	"docsearch.startScreen.favoriteSearchesTitle": "Favorite",
   	"docsearch.startScreen.removeFavoriteSearchButtonTitle": "Remove this search from favorites",

   	"docsearch.errorScreen.titleText": "Unable to fetch results",
   	"docsearch.errorScreen.helpText": "You might want to check your network connection.",

   	"docsearch.footer.selectText": "to select",
   	"docsearch.footer.selectKeyAriaLabel": "Enter key",
   	"docsearch.footer.navigateText": "to navigate",
   	"docsearch.footer.navigateUpKeyAriaLabel": "Arrow up",
   	"docsearch.footer.navigateDownKeyAriaLabel": "Arrow down",
   	"docsearch.footer.closeText": "to close",
   	"docsearch.footer.closeKeyAriaLabel": "Escape key",
   	"docsearch.footer.searchByText": "Search by",

   	"docsearch.noResultsScreen.noResultsText": "No results for",
   	"docsearch.noResultsScreen.suggestedQueryText": "Try searching for",
   	"docsearch.noResultsScreen.reportMissingResultsText": "Believe this query should return results?",
   	"docsearch.noResultsScreen.reportMissingResultsLinkText": "Let us know."
   }
   ```

</Steps>
